package com.wg.db.repository.code;

import java.io.Serializable;
import java.util.List;
import java.util.Optional;

/**
 * 通用仓库接口，定义基础CRUD操作
 *
 * @param <Key> 实体ID类型（需实现Serializable）
 * @param <T>   实体类型
 */
public interface IRepository<Key extends Serializable, T> {

    /**
     * 根据ID查询实体（存在返回实体，不存在返回空Optional）
     *
     * @param id 实体ID
     * @return 包含实体的Optional
     */
    Optional<T> findById(Key id);

    /**
     * 查询所有实体（无数据返回空列表）
     *
     * @return 实体列表
     */
    List<T> findAll();

    /**
     * 根据组ID查询实体（组ID关联业务分组逻辑）
     *
     * @param groupId 组ID
     * @return 符合条件的实体列表
     */
    List<T> findByGroupId(Serializable groupId);

    /**
     * 自定义SQL查询实体（需确保SQL安全性，避免注入）
     *
     * @param sql 自定义SQL语句
     * @return 符合条件的实体列表
     */
    List<T> findBySql(String sql);

    /**
     * 插入单条实体（不存在则新增）
     *
     * @param entity 待插入实体
     */
    void insert(T entity);

    /**
     * 批量插入实体（高效批量写入）
     *
     * @param entities 实体列表（过滤null后处理）
     */
    void batchInsert(List<T> entities);

    /**
     * 更新单条实体（存在则更新，不存在可配置为插入或忽略）
     *
     * @param entity 待更新实体
     */
    void update(T entity);

    /**
     * 批量更新实体（高效批量更新）
     *
     * @param entities 实体列表（过滤null后处理）
     */
    void batchUpdate(List<T> entities);

    /**
     * 删除单条实体（根据实体对象）
     *
     * @param entity 待删除实体
     */
    void delete(T entity);

    /**
     * 根据ID删除实体（精确删除）
     *
     * @param id 实体ID
     */
    void deleteById(Key id);

    /**
     * 批量删除实体（根据实体列表）
     *
     * @param entities 实体列表（过滤null后处理）
     */
    void batchDelete(List<T> entities);

    /**
     * 检查实体是否存在（根据ID）
     *
     * @param id 实体ID
     * @return 存在返回true
     */
    boolean existsById(Key id);

    /**
     * 获取待处理操作数量（仅异步仓库有效）
     *
     * @return 异步缓冲区中待处理操作的数量
     */
    int pendingSize();

    /**
     * 关闭仓库资源（释放数据库连接、停止异步线程等）
     */
    void close();
}